ODExtension

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODExtension

Superclasses
ODRefCntObject --> ODObject
Subclasses
ODSemanticInterface and ODSettingsExtension

An object of the ODExtension class represents an extended interface to an OpenDoc object.

Description
The OpenDoc architecture is designed to be extended. You can enhance the capabilities of and communications among your parts or other OpenDoc objects in a compound document by extending the standard OpenDoc interfaces. All subclasses of ODObject (including shapes, facets, frames, documents, windows, and parts) can be extended. A part editor can define an extended interface for any purpose, including extensions to handle text searching, linking, specialized text formatting, database accessing, and specialized graphics processing. You can even use extensions to develop component software that goes well beyond the standard OpenDoc model of parts and compound documents.
The ODExtension class is an abstract superclass that you can subclass to create an extended interface to a base object. For example, the ODSemanticInterface class (page 579) is a subclass of ODExtension. Callers can access an already existing extension object by calling its base object's AcquireExtension method (page 440), which returns a reference to the extension object.
The ODExtension class itself has minimal functionality. Each extension object knows which object it is an extension of and how to release resources in itself and in its base object. Further behavior should be implemented in a subclass of ODExtension.

Overriding Inherited Methods
The following methods are inherited and available for use by your subclass of ODExtension.

somInit
The somInit method initializes the instance variables in a SOM object; it is inherited from the SOMObject class.
If you subclass ODExtension, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should initialize the new instance variables in this extension object. The SOM library calls this method when this extension object is created. You must not do anything that might fail in this method. This limits you to operations like setting pointer variables to null, setting numeric variables to appropriate values, and making similar assignments from constants. If you have any initialization code that can potentially fail, it must be handled in this extension's subclass-specific initialization method; see also the InitExtension method (page 217).

somUninit
The somUninit method disposes of the storage created for a SOM object; it is inherited from the SOMObject class.
If you subclass ODExtension, you can override this method. Your override method does not need to call its inherited method; the inherited method is automatically called for you by the SOM library.
Your override of this method should dispose of any storage created for this extension object, including any storage related to additional instance variables initialized in this extension object. The SOM library calls this method when this extension object is deleted; this method must not fail.

Release
The Release method decrements an object's reference count by 1; it is inherited from the ODRefCntObject class.
void Release ();
If you subclass ODExtension, you can override this method to release an object and reclaim valuable resources like memory. Your override method must call its inherited method at the beginning of your implementation.
A part editor calls this method when it no longer needs a reference to this extension object. If this extension object's reference count becomes 0 and the base object is not null, the base object's ReleaseExtension method is called.

Purge
The Purge method frees memory on request; it is inherited from the ODObject class.
ODSize Purge (in ODSize size);
Every subclass of ODObject can override this method and should do so if it creates caches and temporary buffers. If you subclass ODExtension, you must override this method or risk running out of available memory. Your override method must call its inherited method at some point in your implementation (it does not matter where). You should save the size value returned by the inherited method because you will need it to compute the value to return from your override method.
Your override of this method should free any caches, noncritical buffers, or objects (up to the amount of memory specified). Your override of this method should add the number of bytes actually freed to the number returned by the inherited method and return the sum as the total amount of memory released. OpenDoc calls this method in low-memory situations; you should not allocate memory for this operation.

Methods
This section presents summary descriptions of the ODExtension methods grouped according to purpose, followed by detailed descriptions in alphabetical order.
Initializing

InitExtension
Initializes this extension object.
Base-Object Manipulation

GetBase
Returns a reference to this extension's base object.
BaseRemoved
Invalidates this extension object.
Extension Characteristics

CheckValid
Checks whether this extension object is valid and generates an exception if it is not valid.
IsValid
Returns a Boolean value that indicates whether this extension object is valid.

Methods
BaseRemoved
CheckValid
GetBase
InitExtension
IsValid